SideButton Marketing Website Connect (Extension Auth) — Knowledge Module Reference

What This Is

Standalone authentication page for the SideButton Chrome extension. No Header or Footer -- a minimal centered card with email/password form on a light gradient background. After successful login, credentials (email, userCode, mcpUrl) are sent to the extension via three methods (chrome.runtime.sendMessage, window.postMessage, localStorage), then the page shows a success view with green checkmark and auto-closes after 2.5 seconds. The page also displays hardcoded test credentials for Phase 1 development.

URL Patterns

Pattern	Description
/connect	Extension auth page (no extension messaging)
/connect?ext={extensionId}	With extension ID for chrome.runtime.sendMessage

Page Structure

+--[Full viewport, centered, no Header/Footer]------+
|  Background: linear-gradient #F8FAFC → #F1F5F9    |
|                                                     |
|  +--[.card — white, rounded-16, shadow, 400px]---+ |
|  |                                                 | |
|  |  [#loginForm]                                   | |
|  |    [.header]                                    | |
|  |      [.logo] 56×56 green gradient, bolt icon    | |
|  |      H1: "Sign in to SideButton"               | |
|  |      P.subtitle: "Connect your browser to       | |
|  |                    Claude Desktop"              | |
|  |                                                 | |
|  |    [.error #error] hidden by default            | |
|  |                                                 | |
|  |    [.form-group]                                | |
|  |      Label "Email" + input#email                | |
|  |    [.form-group]                                | |
|  |      Label "Password" + input#password          | |
|  |                                                 | |
|  |    Button#signInBtn "Sign In"                   | |
|  |                                                 | |
|  |    [.hint] Test credentials (Phase 1)           | |
|  |      [email protected] / demo2026             | |
|  |                                                 | |
|  |  [#successView] hidden by default               | |
|  |    [.success-icon] green circle + checkmark     | |
|  |    "Connected!"                                 | |
|  |    "You can close this tab..."                  | |
|  |                                                 | |
|  |  [.footer-link]                                 | |
|  |    "Back to SideButton" → /                     | |
|  +------------------------------------------------+ |
+-----------------------------------------------------+

Key Elements

Element	Selector	Notes
Card container	.card	White, max-width: 400px, border-radius: 16px, padding: 40px
Logo	.logo	56x56px green gradient square with bolt SVG
Heading	h1	"Sign in to SideButton", font-size: 22px, color #0F172A
Subtitle	.subtitle	"Connect your browser to Claude Desktop", color #64748B
Login form wrapper	#loginForm	Contains all form fields; hidden on success
Error message	#error / .error	Red background #FEF2F2, border #FECACA, display: none by default
Email label	label[for="email"]	"Email"
Email input	input#email	type="email", placeholder "[email protected]", autofocus
Password label	label[for="password"]	"Password"
Password input	input#password	type="password", placeholder "Enter your password"
Sign In button	button#signInBtn	Green gradient #15C39A → #0EA87D, type="button"
Test credentials hint	.hint	Shows [email protected] / demo2026
Success view	#successView	display: none by default, shown after successful auth
Success icon	.success-icon	64x64px green circle with check polyline SVG
Success title	.success-title	"Connected!"
Success text	.success-text	"You can close this tab and return to the extension."
Back link	.footer-link a	"Back to SideButton" → /

Data Model

Field	Type	Description
email	string (email)	User email address, trimmed before submission
password	string	User password, sent as-is
ext (URL param)	string	Chrome extension ID for chrome.runtime.sendMessage

API Request (POST)

Field	Type	Description
email	string	From #email input, trimmed
password	string	From #password input

API Response (success)

Field	Type	Description
ok	boolean	true on success
email	string	Authenticated user email
userCode	string	User identification code
mcpUrl	string	MCP server endpoint URL

API Response (failure)

Field	Type	Description
ok	boolean	false on failure
error	string	Error message (fallback: "Invalid email or password")

localStorage (on success)

Key	Value	Description
sidebutton_auth	JSON string	Contains email, userCode, mcpUrl, timestamp

States & Variations

State	Trigger	Visual Indicator
Default	Page load	Empty form with email (autofocused) and password fields, Sign In button green
Input focused	Click/tab into field	Border changes to #15C39A, background to white, green ring shadow 3px
Client validation error	Click Sign In with empty field(s)	Error div shows "Please enter email and password", button stays enabled
Submitting	Click Sign In with values	Button disabled, gray #94A3B8 background, text "Signing in...", no hover/shadow
Server error	Invalid credentials / API error	Error div shows server message or "Connection failed. Please try again.", button re-enabled, text "Sign In"
Success	Valid credentials	#loginForm hidden, #successView shown with green checkmark, "Connected!" title
Auto-close	2.5s after success	window.close() called (may be blocked by browser if tab was not script-opened)

Responsive Behavior

Breakpoint	Behavior
All widths	Card is max-width: 400px, width: 100%; body has padding: 20px
Mobile (<400px)	Card fills viewport width minus 40px padding; all elements stack vertically
Desktop (>400px)	Card centered in viewport with box-shadow

API Host Resolution

Environment	API Host
Development (localhost / 127.0.0.1)	http://localhost:9877
Production	window.location.origin (same origin via nginx proxy)

Common Tasks

1. Verify form fields present

1. Navigate to /connect
2. Confirm h1 reads "Sign in to SideButton"
3. Confirm .subtitle reads "Connect your browser to Claude Desktop"
4. Confirm input#email exists with placeholder "[email protected]"
5. Confirm input#password exists with placeholder "Enter your password"
6. Confirm button#signInBtn reads "Sign In"

2. Submit form with test credentials

1. Click input#email, type [email protected]
2. Click input#password, type demo2026
3. Click button#signInBtn
4. Verify button text changes to "Signing in..." and becomes disabled
5. Wait for #successView to become visible
6. Verify "Connected!" title appears

3. Verify client-side validation

1. Leave both fields empty
2. Click button#signInBtn
3. Verify #error displays "Please enter email and password"
4. Fill only email, clear password, click Sign In again
5. Verify same error message appears

4. Verify server error handling

1. Type invalid email (e.g., [email protected]) and any password
2. Click button#signInBtn
3. Verify #error shows server error message (e.g., "Invalid email or password")
4. Verify button re-enables with text "Sign In"

5. Verify keyboard navigation

1. Focus input#email, press Enter
2. Verify focus moves to input#password
3. Focus input#password, press Enter
4. Verify form submits (equivalent to clicking Sign In)

6. Verify Back link

1. Click .footer-link a ("Back to SideButton")
2. Verify navigation to / (homepage)

Tips

• The page is a standalone HTML document -- no Astro Layout, Header, or Footer components; no Tailwind CSS classes
• All styling is inline <style> in the <head> -- no external CSS files loaded
• The form does NOT use a <form> element; submit is handled by a click listener on button#signInBtn
• Enter key on email field moves focus to password; Enter key on password field triggers sign-in
• Three credential delivery methods fire in sequence on success: chrome.runtime (if ext param), postMessage, localStorage
• The ext URL parameter is optional -- without it, only postMessage and localStorage methods are used
• Test credentials ([email protected] / demo2026) are displayed in a .hint section below the form
• The autofocus attribute on the email input means it receives focus on page load without any script

Gotchas

• No <form> element: The page uses <div> wrappers and a button[type="button"] -- standard form submission and required attribute validation do not apply; all validation is in the click handler
• window.close() may be blocked: Browsers only allow window.close() on tabs opened by script (window.open); if the user navigated to /connect directly, the auto-close after 2.5s will silently fail
• Client validation is minimal: Only checks for empty fields (!email || !password); no email format validation on the client side (HTML type="email" provides some browser-native validation but is not enforced by the script)
• API host differs by environment: Development uses localhost:9877, production uses same-origin -- tests must account for which environment they run in
• postMessage uses wildcard origin: window.postMessage({...}, "*") sends to all origins -- this is intentional for extension communication but is a security consideration
• No CSRF protection: The form posts directly to the API with no CSRF token; relies on same-origin policy and CORS